/* ========================================================================= */
/* ------------------------------------------------------------------------- */
/*!		
  \file			abstractfilter.h
  \date			Aug 2011
  \author		TNick

  \brief		Contains the definition for AbstractFilter class


 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @n
 Please read ReadMe.txt and Licence.txt in root folder @n
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @n

*/
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
#ifndef __ABSTRACTFILTER_INC__
#define __ABSTRACTFILTER_INC__
//
//
//
//
/*  INCLUDES    ------------------------------------------------------------ */

class       PageData;
class       QWidget;

#include    <QString>
#include    <QList>


/*  INCLUDES    ============================================================ */
//
//
//
//
/*  CLASS    --------------------------------------------------------------- */

/// defines the interface that is used by filters
/**
*	
*/
class AbstractFilter        		{

	//
	//
	//
	//
	/*  DEFINITIONS    ----------------------------------------------------- */

    friend class FiltOpts;

	/*  DEFINITIONS    ===================================================== */
	//
	//
	//
	//
	/*  DATA    ------------------------------------------------------------ */

private:

    // the unique instance
    /*static Flt_RegExNC *       uniq_instance;*/

    /// the list of pages that pass this filter (have a match)
    QList<PageData*>                 filt_in;


protected:

    /// keep track of the filters
    static QList<AbstractFilter*>   filt_list;


	/*  DATA    ============================================================ */
	//
	//
	//
	//
	/*  FUNCTIONS    ------------------------------------------------------- */


protected:
    /// destructor;
    virtual				~AbstractFilter		(void);

public:
    /* methods required to be implemented by the filter */

	
    // function used to create the instance of the filter or return existing
    /*
 *	a single instance is required. As such, we store the pointer on first
 *  call and, on subsequent call, we simple return that pointer.
 *
 *	@return		new / existing instance as pointer
    static AbstractFilter* initFilter		(void);
 */


    /// tell the name of this filter
    virtual QString     name                (void) = 0;

    /// tell if this filter is enabled
    virtual bool        active              (void) = 0;

    /// function that populates a tab with it's options
    /**
      * returned pointer of type void* is used in subsequent opperations
      */
    virtual void*       createOptions       (QWidget * parent) = 0;


    /// function informed that the user pressed OK in options
    /**
      * The implementation is required to save the settings choosen in
      * the options page. @n
      * The function is connected with accepted() signal in FiltOpts class.
      * Each of the registered filters (see registerFilter()) are iterated
      * and asked to save the data in the gui.
      */
    virtual void        saveOptions         (
        QWidget *   parent,     /**< parent widget */
        bool        active_sts, /**< tells wether the user enabled or disabled
                                      the use of this filter */
        void *      data        /**< associated data returned by the
                                createOptions() function */
        ) = 0;


    /// filter a page (tell if it's on the chain or off the chain)
    virtual bool        passesFilter        (PageData * pg_data) = 0;





    /* following methods are implemented by the class */

    /// if the page is in, it should be added to internal list
    bool                addIfPasses         (PageData * pg_data);
    /// if the page is in, it should be removed from internal list
    bool                delIfPasses         (PageData * pg_data);
    /// tell if a page passes this filter
    bool                hasPage             (PageData * pg_data);



    /* static methods used in filters management */


    /// keep track of filters; each one needs to announce it's presence
    /**
      * This function provides the opportunity for dynamically loaded filters. @n
      * To be taken into consideration, an filter first uses this function that
      * does house-keping (like adding new filter instance to a chain).
      * @todo Create counter part function (unregisterFilter())
      * @return the index where this filter was added
      */
    static int          registerFilter      (AbstractFilter * new_filter);

    /// tell if a page passes the filter or not
    /**
      * in order for this function to return true, at least one of the
      * enabled filters (active() == true) must return true on passesFilter()
      */
    static bool         pagePasses           (PageData * pg_data);

    /// terminate all filters (and give them a chance to save internal data)
    static void         killFilters         (void);


	/*  FUNCTIONS    ======================================================= */
	//
	//
	//
	//

};	/*	class AbstractFilter	*/

/*  CLASS    =============================================================== */
//
//
//
//
#endif // __ABSTRACTFILTER_INC__
/* ------------------------------------------------------------------------- */
/* ========================================================================= */
